pzdbCreate
==========

(c) 2006, 2007 Michael Schierl

This program is Free Software according to the GNU General Public 
License, Version 2. You can find this license in the "COPYING" file.

Usage
-----

pzdbCreate can be used to convert .csv files to pzdb .pdb databases.

It requires Java 1.5, available from http://java.sun.com/

Call it on the command line like this ([] means optional):

java -jar pzdbCreate.jar csvfile [dbName [pdbfile]]

The DB name is the name used on the Palm to select the database. If
you do not give a DB name, it will be the same as the filename.  If
you do not give a pdf file name, it will be determined from the DB
name.

Input file format
-----------------

The input file may contain comment lines (lines starting with #)
everywhere. Blank lines are ignored everywhere, too. You may use both
comma and semicolon as column separator, but it has to be consistent
throughout the file. If in doubt, use semicolons since they got much
more testing. If a column contains quotation marks or semicolons
(commas), it has to be quoted with quotation marks. Every quotation
mark inside quotation marks must be doubled.

Example: The text

This is a semicolon: ";", this is a backslash: "\"

has to be written as

"This is a semicolon: "";"",  this is a backslash: ""\"""

The first (non-comment) line is the header line. It must give field
headers and widths, separated by a colon. All field widths must sum up
to exactly 150 pixels; Fields with zero width are not visible on the
main view, only on the details view. Fields with zero width should be
after fields with nonzero width (this improves compression ratio and
performance). In any case, only the first eight fields can be visible.

Example:

50:One;10:Two;90:Three

The following lines are records.  

Both the header and record lines may have additional columns at the
end of the line. These columns must start with a prefix (one or two
letters followed by an equals sign):

T=   additional text line (may occur multiple times; will be added to
     the record's details or to the DB information if used on the
     header line).
F=   load additional text lines from filename
M=   Map filename (only on header line)
CM=  Color map filename (only on header line)
I=   Image filename (b/w or gray)
P=   Picture filename (color image)
     Images will be added to a record or to the DB information
C=   Map coordinates (not on header line), looks like C=20,19

Supported image formats: PNG and JPEG. If the image contains only
colors black and white, it will be embedded as a b/w image, else it
will be embedded as a 4-bit grayscale image (M= or I= option) or
16-bit color picture (CM= or P= option). There may be up to 255
images (including the map) in one database, but only one image
per record (and none if map coordinates are present).


Compatibility
-------------

CSV files used in version 0.2 or earlier are not fully compatible to
the new version. If the records contained backslashes or quotation
marks, quoting syntax has changed (backslashes no longer need to be
doubled, quotation marks need to be doubled instead). Syntax for
database specials like maps or long memo records has changed as
well. On the other hand, CSV files exported from MS Excel (if they
adhere to the column format) should be usable out of the box now.  If
you find one that does not work, please report it as a bug.

Some workarounds needed in previous versions (like putting extra
fields into long records) are no longer necessary since they are
handled automatically now.

Changes
-------

++ 2007-09-22: Version 1.0 released +++

- no changes

++ 2007-09-06: Version 1.0-rc1 released +++

- Code cleanups
- Add more consistency checks
- Store name of map image in .csv file
- Add support for images per record
- Add support for grayscale and color images/maps
- Add support for database information
- Store long memos automatically if needed
  * Move hidden columns to memo automatically if necessary
- Clean up input file syntax
  * Use a better CSV parser that supports commas as delimiters as well
    and should be able to load Excel exported CSVs out of the box
  * Unlimited extra parameters allowed, but they need to have a prefix
  * Maps with M= or CM=
  * Map coordinates with C=
  * Images with I= or P=
  * Memos with T=
  * Memos from file with F=
  * Memo on the header column will become Database information
- Show summary after completed creation
- Add Roundtrip test (passed for all databases I have)

+++ 2006-06-17: Version 0.2 released +++

- use new jPalmDB library for parsing and creating PDB files
- allow adding memos and/or maps to a database
- fixed bugs in pdb2csv conversion
- support memos and maps in pdb2csv conversion

+++ 2006-04-29: Version 0.1 released +++
